/*
 * Copyright (C) 2010 Graham Allan
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

package edu.strath.cis.grallan.findbugs.adaptiveranking;

/**
 * IRankScheme is intended to provide a flexible way for a graphical user interface to represent a
 * rank.
 * 
 * Ranks can be based on any type which has a natural ordering (as obliged by extended
 * {@link Comparable}. Implementing classes should be able to provide a relative position given an
 * instance of <code>T</code>. This represents the placement of <code>T</code> in the overall
 * ranking scheme.
 * 
 * Implementions may or may not explicitly require max > min (by throwing exceptions in the
 * constructor, or return an error value (e.g. {@link Double#NaN} for
 * <code>relativePosition()</code>).
 * 
 * Implementations may provide a continuous or discrete range of ranks.
 * 
 * @author Graham Allan (grallan@cis.strath.ac.uk)
 */
public interface IRankScheme<T extends Comparable<T>> {

	T getMinimum();

	T getMaximum();

	/**
	 * The initial defines a default, neutral rank.
	 */
	T getInitial();

	/**
	 * Given an instance of a rank, this method should return a double representing the position of
	 * the rank within the overall range of ranks. <br>
	 * <br>
	 * For example, if a rank can be a continuous real value between 0 and 10, the position of rank
	 * 6.5 would be 0.65d. <br>
	 * <br>
	 * For continuous values, this is generally calculated as (rank - min) / (max - min). For
	 * discrete values, this is generally (ordinal(rank)) / # of discrete values.
	 * 
	 * 
	 * @param rank
	 * @return
	 */
	double relativePosition(T rank);

}
